home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer)…68k, x86, SPARC, PA-RISC] / NeXTSTEP 3.3 Dev Intel.iso / NextDeveloper / Headers / servers / bootstrap.defs < prev    next >
Text File  |  1991-08-07  |  11KB  |  308 lines
  1. /*
  2.  * bootstrap -- fundamental service initiator and port server
  3.  * Mike DeMoney, NeXT, Inc.
  4.  * Copyright, 1990.  All rights reserved.
  5.  *
  6.  * bootstrap.defs -- Mig interface definition
  7.  */
  8.  
  9. subsystem bootstrap 400;
  10.  
  11. /*
  12.  *    Interface:    Bootstrap server
  13.  *
  14.  *  The bootstrap server is the first user-mode task initiated by the Mach
  15.  *  kernel at system boot time.  The bootstrap server provides two services,
  16.  *  it initiates other system tasks, and manages a table of name-port bindings
  17.  *  for fundamental system services  (e.g. the NetMsgServer, and the Unix
  18.  *  emulation service).
  19.  *
  20.  *  The file /etc/bootstrap.conf is read by bootstrap to determine other system
  21.  *  services to initiate at system boot time.  The format of this file is
  22.  *  described later.
  23.  *
  24.  *  Name-port bindings can be established with the bootstrap server by either 
  25.  *  of two mechanisms:
  26.  *
  27.  *  1.  The binding can be indicated in the file /etc/bootstrap.conf.  In this
  28.  *  case, bootstrap will immediately create a port and bind the indicated name
  29.  *  with that port.  At a later time, a service may "checkin" for the name-port
  30.  *  binding and will be returned receive rights for the bound port.  Lookup's
  31.  *  on bindings created by this mechanism will return send rights to the port,
  32.  *  even if no service has "checked-in".  In this case, requests sent to the
  33.  *  bound port will be queued until a server has checked-in and can satisfy the
  34.  *  request.
  35.  *
  36.  *  2.  Bindings can be established dynamically via a "register" request.  In
  37.  *  this case, the register request provides bootstrap with a name and send
  38.  *  rights for a port.  Bootstrap will provide send rights for the bound port
  39.  *  to any requestor via the lookup request.
  40.  *
  41.  *  Bootstrap provides its service port to descendant tasks via the Mach
  42.  *  "bootstrap" special task port.  All direct descendants of bootstrap receive
  43.  *  a "privileged" bootstrap service port.  System services that initiate
  44.  *  untrusted tasks should replace the Mach bootstrap task special port with
  45.  *  a subset bootstrap port to prevent them from infecting the namespace.
  46.  *
  47.  *  The bootstrap server creates a "backup" port for each service that it
  48.  *  creates.  This is used to detect when a checked out service is no longer
  49.  *  being served.  The bootstrap server regains all rights to the port and
  50.  *  it is marked available for check-out again.  This allows crashed servers to 
  51.  *  resume service to previous clients.  Lookup's on this named port will 
  52.  *  continue to be serviced by bootstrap while holding receive rights for the 
  53.  *  bound port.  A client may detect that the service is inactive via the.
  54.  *  bootstrap status request.  If the service re-registers rather than
  55.  *  "checking-in" the original bound port is destroyed.
  56.  *
  57.  *  The status of a named service may be obtained via the "status" request.
  58.  *  A service is "active" if a name-port binding exists and receive rights
  59.  *  to the bound port are held by a task other than bootstrap.
  60.  *
  61.  *  Bootstrap initiates server tasks and creates initial name-port bindings as
  62.  *  directed by the configuration file /etc/bootstrap.conf.  This file has
  63.  *  entries with the following formats:
  64.  *
  65.  *    services [ SERVICE_NAME ]+ ;
  66.  *
  67.  *        E.g:
  68.  *        services OldService=1 SomeService;
  69.  *
  70.  *        Creates a port and binds the name "OldService" to it.
  71.  *        For compatability, assigns the port via mach_ports_register to
  72.  *        slot 1.  Also creates a port and binds the name "SomeService".
  73.  *
  74.  *    self [ SERVICE_NAME ]+ ;
  75.  *
  76.  *        E.g:
  77.  *        self BootStrapService;
  78.  *
  79.  *        Provides a binding to bootstrap's own service port named
  80.  *        "BootStrapService".
  81.  *
  82.  *    [restartable] server SERVER_FILE_AND_ARGS [ services ... ] ;
  83.  *
  84.  *        E.g:
  85.  *        server "/usr/etc/sigserver -i" services UnixSignalService;
  86.  *
  87.  *        Initiates the server task "/usr/etc/sigserver" with
  88.  *        command-line argument "-i", and also creates a name-port
  89.  *        binding for the name UnixSignalService.  Checkin requests for
  90.  *        UnixSignalService are only accepted via the bootstrap service
  91.  *        port passed to/usr/etc/sigserver.  If the "restartable" option
  92.  *        had been specified, bootstrap will reinitiate the server task
  93.  *        if it receives notification that all of the server's service
  94.  *        ports have been destroyed or deallocated.  The server command
  95.  *        may be specified without surrounding quotes if it does not
  96.  *        include blanks.
  97.  *
  98.  *    init SERVER_FILE_AND_ARGS [ services ... ] ;
  99.  *
  100.  *        E.g:
  101.  *        init /etc/init services NetMsgService=0 PSWindowService=4;
  102.  *
  103.  *        Functions like "server" request above, except process is
  104.  *        started as pid 1.  Illegal if bootstrap itself was not
  105.  *        initiated as pid 1.
  106.  *
  107.  *    forward;
  108.  *
  109.  *        If present, bootstrap will forward unknown lookup requests to
  110.  *        its bootstrap service port (if not PORT_NULL), and forward any
  111.  *        reply to the original requester.
  112.  *
  113.  *    # Comment string up to end of line.
  114.  *
  115.  *        A line terminated comment starts with a sharp sign (#).
  116.  *
  117.  *  Lexical notes:  Strings are either enclosed in double quotes ("), or must
  118.  *  start with a letter or underscore (_) and followed by a string of
  119.  *  alphanumerics and underscores; backslash (\) escapes the following
  120.  *  character.  Strings are limited to a (large) length.  Numbers must be
  121.  *  decimal.  Blanks and newlines may be freely used outside of strings.
  122.  */
  123.  
  124. #include <mach/std_types.defs>
  125. import <servers/bootstrap_defs.h>;
  126.  
  127. type name_t        = (MSG_TYPE_STRING,8*128);
  128. type name_array_t    = ^array [] of name_t;
  129. type bool_array_t    = ^array [] of boolean_t;
  130.  
  131. serverprefix x_;
  132.  
  133. /*  old service_checkin */
  134. skip;
  135. /*  old service_status */
  136. skip;
  137.  
  138. /*
  139.  * kern_return_t
  140.  * bootstrap_check_in(port_t bootstrap_port,
  141.  *             name_t service_name,
  142.  *             port_all_t *service_port)
  143.  *
  144.  * Returns all rights to service_port of service named by service_name.
  145.  *
  146.  * Errors:    Returns appropriate kernel errors on rpc failure.
  147.  *        Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
  148.  *        Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
  149.  *            bootstrap port without privilege.
  150.  *        Returns BOOTSTRAP_SERVICE_ACTIVE, if service has already been
  151.  *            registered or checked-in.
  152.  */
  153. routine bootstrap_check_in(
  154.             bootstrap_port    : port_t;
  155.             service_name    : name_t;
  156.         out    service_port    : port_all_t);
  157.  
  158. /*
  159.  * kern_return_t
  160.  * bootstrap_register(port_t bootstrap_port,
  161.  *              name_t service_name,
  162.  *              port_t service_port)
  163.  *
  164.  * Registers send rights for the port service_port for the service named by
  165.  * service_name.  Attempts to registering a service where an active binding
  166.  * already exists are rejected.  On the otherhand, registering a service where
  167.  * and inactive binding exists (i.e. bootstrap currently holds receive rights
  168.  * for the service port) is allowed; in this case the previous service port
  169.  * will be deallocated.  Restarting services wishing to resume service for
  170.  * previous clients must first attempt to checkin to the service in order to
  171.  * recover the previous service port.
  172.  *
  173.  * Errors:    Returns appropriate kernel errors on rpc failure.
  174.  *        Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
  175.  *            bootstrap port without privilege.
  176.  *        Returns BOOTSTRAP_NAME_IN_USE, if service has already been
  177.  *            register or checked-in.
  178.  */
  179. routine bootstrap_register(
  180.         bootstrap_port    : port_t;
  181.         service_name    : name_t;
  182.         service_port    : port_t);
  183.  
  184. /*
  185.  * kern_return_t
  186.  * bootstrap_look_up(port_t bootstrap_port,
  187.  *            name_t service_name,
  188.  *            port_t *service_port)
  189.  *
  190.  * Returns send rights for the service port of the service named by
  191.  * service_name in service_port.  Service is not guaranteed to be active.
  192.  *
  193.  * Errors:    Returns appropriate kernel errors on rpc failure.
  194.  *        Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
  195.  */
  196. routine bootstrap_look_up(
  197.         bootstrap_port    : port_t;
  198.         service_name    : name_t;
  199.     out    service_port    : port_t);
  200.  
  201. /*
  202.  * kern_return_t
  203.  * bootstrap_look_up_array(port_t bootstrap_port,
  204.  *              name_array_t service_names,
  205.  *              int service_names_cnt,
  206.  *              port_array_t *service_port,
  207.  *              int *service_ports_cnt,
  208.  *              boolean_t *all_services_known)
  209.  *
  210.  * Returns port send rights in corresponding entries of the array service_ports
  211.  * for all services named in the array service_names.  Service_ports_cnt is
  212.  * returned and will always equal service_names_cnt (assuming service_names_cnt
  213.  * is greater than or equal to zero).
  214.  *
  215.  * Errors:    Returns appropriate kernel errors on rpc failure.
  216.  *        Returns BOOTSTRAP_NO_MEMORY, if server couldn't obtain memory
  217.  *            for response.
  218.  *        Unknown service names have the corresponding service port set
  219.  *            to PORT_NULL.
  220.  *        If all services are known, all_services_known is true on
  221.  *            return, if any service is unknown, it's false.
  222.  */
  223. routine bootstrap_look_up_array(
  224.         bootstrap_port    : port_t;
  225.         service_names    : name_array_t;
  226.     out    service_ports    : port_array_t;
  227.     out    all_services_known: boolean_t);
  228.  
  229. /*  old bootstrap_get_unpriv_port */
  230. skip;
  231.  
  232. /*
  233.  * kern_return_t
  234.  * bootstrap_status(port_t bootstrap_port,
  235.  *            name_t service_name,
  236.  *            boolean_t *service_active);
  237.  *
  238.  * Returns: service_active is true if service is available.
  239.  *            
  240.  * Errors:    Returns appropriate kernel errors on rpc failure.
  241.  *        Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
  242.  */
  243. routine bootstrap_status(
  244.         bootstrap_port    :    port_t;
  245.         service_name    :    name_t;
  246.     out    service_active    :    boolean_t);
  247.  
  248. /*
  249.  * kern_return_t
  250.  * bootstrap_info(port_t bootstrap_port,
  251.  *          name_array_t *service_names,
  252.  *          int *service_names_cnt,
  253.  *          name_array_t *server_names,
  254.  *          int *server_names_cnt,
  255.  *          bool_array_t *service_active,
  256.  *          int *service_active_cnt);
  257.  *            
  258.  * Errors:    Returns appropriate kernel errors on rpc failure.
  259.  */
  260. routine bootstrap_info(
  261.         bootstrap_port    : port_t;
  262.     out    service_names    : name_array_t, dealloc;
  263.     out server_names    : name_array_t, dealloc;
  264.     out service_active    : bool_array_t, dealloc);
  265.  
  266. /*
  267.  * kern_return_t
  268.  * bootstrap_subset(port_t bootstrap_port,
  269.  *            port_t requestor_port,
  270.  *            port_t *subset_port);
  271.  *
  272.  * Returns a new port to use as a bootstrap port.  This port behaves
  273.  * exactly like the previous bootstrap_port, except that ports dynamically
  274.  * registered via bootstrap_register() are available only to users of this
  275.  * specific subset_port.  Lookups on the subset_port will return ports
  276.  * registered with this port specifically, and ports registered with
  277.  * ancestors of this subset_port.  Duplications of services already
  278.  * registered with an ancestor port may be registered with the subset port
  279.  * are allowed.  Services already advertised may then be effectively removed
  280.  * by registering PORT_NULL for the service.
  281.  * When it is detected that the requestor_port is destroied the subset
  282.  * port and all services advertized by it are destroied as well.
  283.  *
  284.  * Errors:    Returns appropriate kernel errors on rpc failure.
  285.  */
  286. routine bootstrap_subset(
  287.         bootstrap_port    : port_t;
  288.         requestor_port    : port_t;
  289.     out    subset_port    : port_t);
  290.  
  291. /*
  292.  * kern_return_t
  293.  * bootstrap_create_service(port_t bootstrap_port,
  294.  *              name_t service_name,
  295.  *              port_t *service_port)
  296.  *
  297.  * Creates a service named "service_name" and returns send rights to that
  298.  * port in "service_port."  The port may later be checked in as if this
  299.  * port were configured in the bootstrap configuration file.
  300.  *
  301.  * Errors:    Returns appropriate kernel errors on rpc failure.
  302.  *        Returns BOOTSTRAP_SERVICE_ACTIVE, if service already exists.
  303.  */
  304. routine bootstrap_create_service(
  305.         bootstrap_port    : port_t;
  306.         service_name    : name_t;
  307.     out    service_port    : port_t);
  308.